home *** CD-ROM | disk | FTP | other *** search
/ Shareware Super Platinum 8 / Shareware Super Platinum 8.iso / mac / PROGTOOL / DDPLUS63.ZIP;1 / DOORTUT1.DOC < prev    next >
Encoding:
Text File  |  1991-09-18  |  10.8 KB  |  260 lines
  1. ------------------------------------------------------------------------------
  2. Note: This article extracted from the September '91 issue of Carrier Detect
  3.       Journal. At this time, only part 1 of the series was available; Future
  4.       installments may be read in Carrier Detect Journal.
  5. ------------------------------------------------------------------------------
  6.  
  7.           *   Writing a BBS Door (Part 1)
  8.               Tutorial by Scott M. Baker
  9.  
  10.  
  11.               Doors are programs written for a bulletin board system
  12.           to allow the user to perform other tasks than the bulletin
  13.           board  software  allows.   For example,  a  door  could be
  14.           anything  from a  bbs lister  to a  multiplayer simulation
  15.           (such  as  Galactic Warzone,  Yankee  Trader,  Trade Wars,
  16.           etc).  This  article will  be a  tutorial on  how to write
  17.           door  programs.  The  programs will  be  written  in Turbo
  18.           Pascal (version  5.5 or  6.0) and  will use  my DoorDriver
  19.           routines to  provide support for  RBBS, QuickBBS, Wildcat,
  20.           WWIV, etc.
  21.  
  22.               Right  now,  we're   just  going  to   stick  with  my
  23.           DoorDriver routines since they are  the routines that I am
  24.           most familiar with. In  the future, we may  explore a C or
  25.           basic  door  library,  or  another  Pascal  library.  This
  26.           article is the  first in a series  about Door Writing. I'm
  27.           not sure yet how many articles we have. If there isn't any
  28.           support for this column, then  it'll probably be just two.
  29.           If a lot of response comes in, then we'll continue as long
  30.           as I have time to continue writing.
  31.  
  32.  
  33.  
  34.                                  REQUIREMENTS
  35.  
  36.           What you'll need:
  37.  
  38.           - Turbo Pascal by Borland. Either version 5.5 or
  39.             6.0 will do.
  40.  
  41.           - DOORDR40.ZIP. This is my Doordriver support
  42.             package for TP5.5 and TP6.0. It includes async
  43.             support, bbs interfacing, etc. Available from
  44.             my bbs (602-577-3650) as well as several other
  45.             sites.
  46.  
  47.             - A basic understanding of Pascal (specifically
  48.             Turbo   Pascal).  You   don't  need   to  be   a  Pascal
  49.             wizard or anything, but the more knowledge you
  50.             have, the better.
  51.  
  52.                           BASIC ELEMENTS OF A 'DOOR'
  53.  
  54.           Ok, time to  get started. First lets  talk about the basic
  55.           elements that a door needs.
  56.  
  57.           1) Async communications support.
  58.  
  59.           The door  must be  able to  talk to  the user  through the
  60.           communications  port.   Support  has  to  be  provided for
  61.           multiple com ports,  locked baud rates,  etc.  The program
  62.           also must monitor the presence of the CARRIER DETECT modem
  63.           line to  make sure  the carrier  is not  dropped while the
  64.           door is in use.
  65.  
  66.           2) BBS software interfacing.
  67.  
  68.           The door needs  to be able  to grab the  user's name, time
  69.           left,  and  other  associated  information  from  the  bbs
  70.           software.  Since bbs  programs lack standardization, there
  71.           are several  different methods  that have  to be accounted
  72.           for.
  73.  
  74.           3) Support for ANSI (color) graphics and animation.
  75.  
  76.           Just about every door has ANSI capabilities these    days,
  77.           so if  you want  yours to  be seriously  considered, you'd
  78.           better have it as well.
  79.  
  80.           Doordriver  will  handle  the  first  two  points  for you
  81.           automatically when  you call  the INITDOORDRIVER procedure
  82.           described  below.  Doordriver has  support  for  the third
  83.           point (ANSI graphics), but you'll need to use your own
  84.           skills  in deciding  where you  wish  to put  colors, what
  85.           colors to use, etc.
  86.  
  87.  
  88.                             DOORDRIVER PROCEDURES
  89.  
  90.  
  91.           There  are a  series  of procedures  that  doordriver will
  92.           provide  to you  for  accomplishing these  tasks.  Without
  93.           getting too complex, let's discuss a few of them:
  94.  
  95.               PROCEDURE INITDOORDRIVER(ctl_file_name: string);
  96.  
  97.           This procedure  initializes the door  support system, comm
  98.           port,  grabs  the user  name,  and a  few  other necessary
  99.           things.    The  variable   "ctl_file_name"  is   a  string
  100.           containing the  name of  the control  file that  your door
  101.           will use.  For now, let's just ignore the control file and
  102.           use the sample included with the DD package.
  103.  
  104.               PROCEDURE SWRITE(out_str: string);
  105.  
  106.           This is DD's compliment to  the Write() statement of Turbo
  107.           Pascal.  The "S"  stands for simultaneous.  Output will be
  108.           written to both the remote user (through the com port) and
  109.           the local screen.  "out_str" is the  string containing the
  110.           data  you wish  to write.   Most of  your output  will use
  111.           either this or the following SWRITELN procedure.
  112.  
  113.               PROCEDURE SWRITELN(out_str: string);
  114.  
  115.           Same  as SWRITE,  except  a carriage  return/line  feed is
  116.           appended to  the end  of the  string.  This  is similar to
  117.           TP's writeln statement.
  118.  
  119.               variable USER_FIRST_NAME: STRING;
  120.  
  121.           After INITDOORDRIVER  has been called,  this variable will
  122.           contain the  user's first  name.  The  string will  be all
  123.           upper-case.
  124.  
  125.               variable USER_LAST_NAME: STRING;
  126.  
  127.           Similar to USER_FIRST_NAME, this variable will contain the
  128.           user's last name.  As with USER_FIRST_NAME, it is only
  129.           valid after the call to INITDOORDRIVER has been made.
  130.  
  131.  
  132.  
  133.                                YOUR FIRST DOOR
  134.  
  135.  
  136.           Now  that  you've  seen  a  few  of  doordriver's  support
  137.           routines, lets put them to  work in the "hello door."  The
  138.           hello door will  be simply a door  version of the standard
  139.           hello program.  Meaning that  it displays "hello world" to
  140.           the screen.  First, a note  about my code, I'll be placing
  141.           line  numbers  ({1}, {2},  etc)  in the  code.   These are
  142.           intended for discussion purposes and are not needed in the
  143.           pascal program itself.
  144.  
  145.           HLODOOR.PAS:
  146.  
  147.           {1} Program HelloDoor;
  148.           {2}
  149.           {3} uses crt, doordriv;
  150.           {4}
  151.           {5} begin
  152.           {6}   InitDoorDriver('Doordriv.CTL');
  153.           {7}   swriteln('Hello World!');
  154.           {8}   delay(5000);
  155.           {9} end.
  156.  
  157.           Experienced pascal programmers will feel a bit insulted by
  158.           the simplicity of the above program, but it is a necessary
  159.           step in learning to use door driver.
  160.  
  161.  
  162.                         COMPILING AND RUNNING THE DOOR
  163.  
  164.  
  165.           Once you've got  that typed in, then  it's time to compile
  166.           HLODOOR.  Using either Turbo Pascal version 5.5 or version
  167.           6.0, compile the program to  disk.  If all goes well, then
  168.           you'll  be  left  with  HLODOOR.EXE  on  your  hard drive.
  169.           Doordriv.doc  (supplied with  doordriver)  includes infor-
  170.           mation on how to configure /  run the door on your system.
  171.           For now, let's just worry  about running the door in local
  172.           mode.  For local mode, type  "/L" on the command line. For
  173.           example, "HLODOOR  /L" will run  HLODOOR. Since  you are a
  174.           local user,  the door will  prompt you for  your first and
  175.           last name.  A remote  user's information would be gathered
  176.           from  the  bbs information  file  (i.e.  DORINFOx.DEF). We
  177.           won't worry about that for now.
  178.  
  179.  
  180.                                ANALYSIS OF CODE
  181.  
  182.  
  183.           Now lets  go through  the important  lines of  code one by
  184.           one.
  185.  
  186.               LINE 3: Uses crt, DoorDriv;
  187.  
  188.           The "uses" statement  is required by  Turbo Pascal to tell
  189.           TP  which  units we  will  be using.   Obviously,  we need
  190.           "doordriv" for DD's procedures.  "crt" is required because
  191.           we use the DELAY procedure.
  192.  
  193.               LINE 6: InitDoorDriver('DoorDriv.CTL');
  194.  
  195.           This  is   that  all-important   initialization  statement
  196.           described  somewhere above.   It  tells doordriver  to get
  197.           things all set up and  working.  The 'Doordriv.CTL' is the
  198.           name of that "control file" and we won't pay any attention
  199.           to it for now.
  200.  
  201.               LINE 7: swriteln('Hello World!');
  202.  
  203.           This is our  screen output.  It'll  write "Hello World" to
  204.           both the  user and the  local screen.   Since its SWRITELN
  205.           and not SWRITE, a carriage  return and line feed also will
  206.           be sent.  There are several ways that this could have been
  207.           done. For example:
  208.  
  209.             {1}   swrite('Hello');
  210.             {2}   swriteln(' World!');
  211.  
  212.               - - - or - - -
  213.  
  214.             {1}   swrite('Hello');
  215.             {2}   swrite(' World!');
  216.             {3}   swriteln('');
  217.  
  218.           The output will be the same in the above situations.
  219.  
  220.               LINE 8: Delay(5000);
  221.  
  222.           This routine  is provided  by Borland  and will  cause our
  223.           program to delay  so you can see  the "hello world" before
  224.           doordriver exits and clears the screen.  The string "Hello
  225.           World!" looks pretty  plain, doesn't it?   Maybe we should
  226.           put something a bit more impressive in, such as the user's
  227.           name.    This   would    involve   using   the   variables
  228.           USER_FIRST_NAME  and USER_LAST_NAME.  The  modification is
  229.           simple enough:
  230.  
  231.               Change line 7 from:
  232.  
  233.               {7} swriteln('Hello World!');
  234.  
  235.               to:
  236.  
  237.               {7} swriteln('Hello, '+user_first_name+' '+
  238.                   user_last_name+'!');
  239.  
  240.           As you may have noticed, I  used plus signs (+) instead of
  241.           commas  (,)  to  separate  the  string  parameters  in the
  242.           SWRITELN line.  With a standard WRITELN statement, you may
  243.           use as many  variables as you wish,  but with SWRITELN, we
  244.           are  limited  to  1 string  variable.   The  point  is, TP
  245.           requires us  to merge  our string  variables together with
  246.           the plus sign.
  247.  
  248.                                   CONCLUSION
  249.  
  250.               That's about all the space we have for now.  Until our
  251.           next  release, play  around with  the SWRITE  and SWRITELN
  252.           procedures and see  what neat things you  can write to the
  253.           screen.   Next time,  we'll  dive deeper  into  some inte-
  254.           ractive communication  with the  user (i.e.  we'll ask him
  255.           something and then write in back to the screen) as well as
  256.           play with some more of DD's internal variables.
  257.  
  258.  
  259.               Contents copyright (c) Carrier Detect Journal.
  260.